---
id: translation-api
title: Translation API
description: Translation API | Transloco Angular i18n
---

Below is a list of the `TranslocoService` API and their usages:

### `translate()`
Translate the given key. Sometimes you may need to translate a key in a component or a service. To do so, you can inject the `TranslocoService` and use its `translate` method:
```ts title="app.component.ts"
export class AppComponent {
  constructor(private translocoService: TranslocoService) {}

  ngOnInit() {
    this.translocoService.translate('hello');
    this.translocoService.translate('hello', { value: 'world' });
    this.translocoService.translate(['hello', 'key']);
    this.translocoService.translate('hello', params, 'es');

    // Translate a key from a specific scope
    this.translocoService.translate('hello', params, 'todos/en');
  }
}
```

:::important
Note that in order to safely use this method, you are responsible for ensuring that the translation files have been successfully loaded by the time it's called.
:::

If you aren't sure, you can use the `selectTranslate()` method instead:

### `selectTranslate()`
Returns an `observable` that when subscribed loads the translation file and emits the translation of the given key:

```ts title="app.component.ts"
export class AppComponent {
  constructor(private translocoService: TranslocoService) {}

  // Don't forget to unsubscribe
  ngOnInit() {
    this.translocoService.selectTranslate('hello')
                         .subscribe(value => ...);

    this.translocoService.selectTranslate('hello', params)
                         .subscribe(value => ...);

    this.translocoService.selectTranslate('hello', params, lang)
                         .subscribe(value => ...);
  }
}
```

`selectTranslate` will emit each time the active language is changed.

You can also select a translation from `scope`, simply inject the scope using the `TRANSLOCO_SCOPE` token
and provide it to the `selectTranslate` function:

```ts title="app.component.ts"
export class AppComponent {
  constructor(private translocoService: TranslocoService,
              @Inject(TRANSLOCO_SCOPE) private scope
  ) {}

  ngOnInit() {
    this.translocoService.selectTranslate('title', params, this.scope)
                          .subscribe(console.log);
  }
}
```

### `translateObject()`

```json title="en.json"
{
  "home": "Home",
  "hello": "Hello {{ name }}",
  "some": {
    "object": {
      "hi": "Hi",
      "hey": "Hey"
    }
  },
  "path": {
    "to": {
      "object": {
         "welcome": "Welcome {{ name }}",
         "nested": {
            "subscribe": "subscribe today for {{ price }}$"
         }
      }
    }
  }
}
```

The following code is based on the `en.json` above ☝

- Returns an `object` based on the given path:

```ts title="app.component.ts"
export class AppComponent {
  constructor(private translocoService: TranslocoService) {}

  ngOnInit() {
    let result = this.translocoService.translateObject('some.object');
    expect(result).toEqual({
      hi: "Hi",
      hey: "Hey"
    });

    /* When querying an object that should be transpiled */
    result = this.translocoService.translateObject('path.to.object', {
      welcome: { value: 'John' },
      'nested.subscribe': { price: 100 }
    });
    expect(result).toEqual({
      welcome: "Welcome John",
      nested: {
        "subscribe": "subscribe today for 100$"
    }});
  }
}
```

- Given a `key: params` map (`object` | `Map`), returns an `array` of translated values:

```ts title="app.component.ts"
export class AppComponent {
  constructor(private translocoService: TranslocoService) {}

  ngOnInit() {
    /* If there are no parameters to transpile pass an empty `object` or `null` */
    let keyParams = {
      home: null, // {}
    }
    let result = this.translocoService.translateObject(keyParams);
    expect(result).toEqual(["Home"]);

    /* When querying an object that should be transpiled */
    keyParams = {
       home: null,
       hello: { name: 'John' },
    }
    result = this.translocoService.translateObject(keyParams);
    expect(result).toEqual(["Home", "Hello John"]);

    /* Works with object paths */
    keyParams = {
       hello: { name: 'John' },
       'path.to.object.nested': {subscribe: {price: 100}}
    }
    result = this.translocoService.translateObject(keyParams);
    expect(result).toEqual([ "Home", { subscribe: "subscribe today for 100$" }]);

    /* Works with `Map` */
    keyParams = new Map();
    keyParams.set('home', null);
    result = this.translocoService.translateObject(keyParams);
    expect(result).toEqual(["Home"]);
  }
}
```

:::important
Note that in order to safely use this method, you are responsible for ensuring that the translation files have been successfully loaded by the time it's called.
:::

If you aren't sure, you can use the `selectTranslateObject()` method instead:

### `selectTranslateObject()`
Load the translation file (if not loaded yet) and behaves the same as `translateObject`.
The only difference is that this method returns an observable to which you can subscribe.

The following code is based on the `en.json` in `translateObject` ☝

```ts title="app.component.ts"
export class AppComponent {
  constructor(private translocoService: TranslocoService) {}

  ngOnInit() {
    this.translocoService.selectTranslateObject('path.to.object', {
      welcome: { value: 'John' },
      'nested.subscribe': { price: 100 }
    }).subscribe(result => {
      expect(result).toEqual({
        welcome: "Welcome John",
        nested: {
          "subscribe": "subscribe today for 100$"
        }
      });
    });

    keyParams = {
      hello: { name: 'John' },
      'path.to.object.nested': {subscribe: {price: 100}}
    }
    this.translocoService.selectTranslateObject(keyParams)
    .subscribe(result => {
       expect(result).toEqual(["Home", { subscribe: "subscribe today for 100$" }]);
    });
  }
}
```

### `getTranslation()`
Returns the selected language translation or a scope translation, if a language isn't passed, the method will return the entire translation map:
```ts title="app.component.ts"
export class AppComponent {
  constructor(private translocoService: TranslocoService) {}

  ngOnInit() {
    this.translocoService.getTranslation();
    this.translocoService.getTranslation('es');
    this.translocoService.getTranslation('todos/es');
  }
}
```

### `selectTranslation()`
Returns an `observable` that when subscribed loads and emits the given language translation object, if no language is passed the active language will be used.  
This method can also be used to retrieve a scope translation object:

```ts title="app.component.ts"
export class AppComponent {
  constructor(private translocoService: TranslocoService) {}

  // Don't forget to unsubscribe
  ngOnInit() {
    this.translocoService.selectTranslation('es')
                         .subscribe(console.log);
                         
    this.translocoService.selectTranslation('todos/es')
                         .subscribe(console.log);
                                                                    
    // Will emit a new value on language changes.                     
    this.translocoService.selectTranslation()
                         .subscribe(console.log);
                                                         
    this.translocoService.selectTranslation('todos')
                         .subscribe(console.log);   
  }
}
```

### `setTranslation()`
Manually sets a translations object to be used for a given language, set merge to true if you want to append the translations instead of replacing them:

```ts title="app.component.ts"
export class AppComponent {
  constructor(private translocoService: TranslocoService) {}

  ngOnInit() {
   this.translocoService.setTranslation({ key: value });
   this.translocoService.setTranslation({ ... }, 'es');
   this.translocoService.setTranslation({ ... }, 'en', { merge: false } );

   // Set a scope
   this.translocoService.setTranslation({ ... }, 'todos/en');
  }
}
```

### `setTranslationKey()`
Sets the translated value of a key. If a language isn't specified in the third parameter, it sets the key value for the current active language:
```ts title="app.component.ts"
export class AppComponent {
  constructor(private translocoService: TranslocoService) {}

  ngOnInit() {
    this.translocoService.setTranslationKey('key', 'value');
    this.translocoService.setTranslationKey('key.nested', 'value');
    this.translocoService.setTranslationKey('key', 'value', 'en');
    this.translocoService.setTranslationKey('key', 'value', 'en', { emitChange: false });
  }
}
```

### `events$`
Subscribe to the translation loading events:

```ts title="app.component.ts"
export class AppComponent {
  constructor(private translocoService: TranslocoService) {}

  ngOnInit() {
    this.translocoService.events$.pipe(
      filter(e => e.type === 'translationLoadSuccess'),
      pluck('payload')
    ).subscribe(({ langName, scope }) => ...);

    this.translocoService.events$.pipe(
      filter(e => e.type === 'translationLoadFailure'),
      pluck('payload')
    ).subscribe(({ langName, scope }) => ...);
    
    this.translocoService.events$.pipe(
      filter(e => e.type === 'langChanged'),
      pluck('payload')
    ).subscribe(({ langName, scope }) => ...);
}
```

:::important
Note that these events will only fire when the translation is loaded from the server, meaning that when switching from a given lang and back won't trigger the events again since the language is loaded from the cache. 
:::
